<li> <a href="#ACORN">Using !Hypermail on the RISC PC</a>
<li> <a href="#2">Usage</a>
<li> <a href="#3">Command-Line Options</a>
<ul>
<li> <a href="#3.1">Input and Output Options</a>
<li> <a href="#3.2">Archive Interface Options</a>
<li> <a href="#3.3">Updating Options</a>
<li> <a href="#3.4">Miscellaneous Options</a>
</ul>
<li> <a href="#4">Configuration Options</a>
<li> <a href="#5">Other Things</a>
<li> <a href="#6">Getting Hypermail</a>
</ul>
<p>
<hr>
<a name="1"><h1>What is Hypermail?</h1></a>
<b>Hypermail</b> is a program that takes a file of mail messages in UNIX mailbox format and generates a set of cross-referenced HTML documents. Each file that is created represents a separate message in the mail archive and contains links to other articles, so that the entire archive can be browsed in a number of ways by following links. Archives generated by Hypermail can be incrementally updated, and Hypermail is set by default to only update archives when changes are detected.
<p>
Each HTML file that is generated for a message contains (where applicable):
<p>
<ul>
<li> the subject of the article,
<li> the name and email address of the sender,
<li> the date the article was sent,
<li> links to the next and previous messages in the archive,
<li> a link to the message the article is in reply to, and
<li> a link to the message next in the current thread.
</ul>
<p>
In addition, Hypermail will convert references in each message to email addresses and URLs to hyperlinks so they can be selected. Email addresses can be converted to <code>mailto:</code> URLs or links to a CGI mail program. Note that not all World-Wide Web browsers support the <code>mailto:</code> URL yet.
<p>
To complement each set of HTML messages, four index files are created which sort the articles by date received, thread, subject, and author. Each entry in these index files are links to the individual articles and provide a bird's-eye view of every archived message.
<p>
Hypermail was originally developed and designed by Tom Gruber for <a href="http://www.eit.com/">Enterprise Integration Technologies</a> (EIT) in Common Lisp. It was later rewritten in C by Kevin Hughes at EIT.
<p>
To see what Hypermail can do, take a look at these Hypermail-produced archives:
<p>
<ul>
<li> <a href="http://www.eit.com/www.lists/">Current www-talk archives</a>, for technical Web talk
<!-- <li> <a href="http://www.eit.com/mailinglists/www-courseware/archive/">www-courseware</a>, for discussion on Web courseware -->
<!-- <li> <a href="http://www.eit.com/mailinglists/www-literature/archive/">www-literature</a>, for discussion on Web literature -->
</ul>
<p>
<hr>
<a name="ACORN"><h1>Using !Hypermail on the RISC PC</h1></a>
<b>!Hypermail</b> is a version of Hypermail which runs on Acorn's RISC PC
(and should run on earlier Acorn machines). All the options set out in this
document are available to command line users, but the program is set up by
default in the following way:
<UL>
<LI>The default input file is that used by ANT's InetSuite, ie,
<CODE>Mail:Mail.INBOX</CODE> (where <CODE>Mail$Path</CODE> is set by
<b>!MarcelDir</b>) .
<LI>Doublc-clicking on !Hypermail will run the program and put individual
mail messages, formatted as HTML (and given the file-type HTML), in various
directories in <CODE>HyperMail:files</CODE>. The program indexes the
messages and these index files will be found in the directory
<CODE>HyperMail:indexes</CODE>.
<li>The file <a
href="file://localhost/HyperMail:Config"><code>HyperMail:config</code></a> can be
altered to change the defaults--for more details see <a
href="#4">Configuration Options</a> below.
<LI>The <code>!Run</code> file simply runs the program in a task window
and then <code>filer_run</code>s the index file; this should appear in a Web
browser (provided that one has been seen by the computer).
<LI>!Help from !Hypermail should run the file you are now reading if the
program itself has not been run (and so there is no index file). Otherwise
it should load the index file. (However the !Help file itself, which is an
<CODE>obey</CODE> file, uses the <CODE>ifthere</CODE> command which I think
was only introduced in RO3.5 and so will need altering for earlier versions
of the OS.)
<LI>The program may well get confused if some messages are deleted from the
<CODE>INBOX</CODE>. It may well be best to delete all the files in
<CODE>HyperMail:files</CODE> if messages are deleted from the
<CODE>INBOX</CODE> and then run the program again. It can also get confused
by badly formed messages.
<LI>The program suffers from many deficiencies in comparison with other
Acorn Mail Readers. For example it does not understand file attachments and
indeed sometimes thinks that a line in a uuencoded file is a mail address
(and so adds a <CODE>mailto:</CODE> tag to it!): this of course makes the
uucencoded file completely useless.
<li>Further, it does not contain a mailer. It does, however, use the
<CODE>mailto:</CODE> command which will be picked up by !Marcel and
probably by other mailers.
<li>It does, however, show what can be done with mailer-reading programs.
My own view is that all the existing Acorn mail readers produce rather
boring-looking output. Turning the text into HTML makes messages look much
better. It appears from the licence---details of where to obtain the full
licence are set out <a href="#6">below</a>, while the <a
href="file://localhost/HyperMail:Docs/swfaq"><code>FAQ</code></a> is in the
<code>docs</code> directory---that there is no charge even for commercial use of
the program. Perhaps the authors of the existing mailers could incorporate
the code into their programs.
<LI>I must emphasise that I am a rank amateur so far as programming is
concerned and so the program is very likely to crash (and I am very unlikely
to know why it has done so).
<STRONG>Do not in any circumstances</STRONG> use !Hypermail to store
valuable mail messages.
<li> The source code is, of course, included. (There
are details of the alterations I have made to the original code in <a
To tell Hypermail what mailbox to read in, use the <b>-m</b> option. If articles will be sent to Hypermail through standard input, use the <b>-i</b> option. Note that the <b>-m</b> and <b>-i</b> options can't be used together! By default, Hypermail will look for a file called <code>mbox</code> to read its articles in from.
<p>
The <b>-d</b> option specifies the directory to put the HTML files and index files that are created into. If the directory doesn't exist, a new one will be created with the name that is specified. If the <b>-d</b> option isn't used, Hypermail will look for a directory with the same name as the mailbox or will create one if needed.
<p>
<pre>
example 1: hypermail -m "www-talk" -d "/archives/www-talk"
example 2: cat "/var/spool/mail/foo" | hypermail -i
</pre>
<p>
<ol>
<li> This example reads the articles in <code>www-talk</code> and will save the output in the <code>/archives/www-talk</code> directory.
<p>
<li> This reads the file <code>/var/spool/mail/foo</code> from standard input and will save the output in a directory called <code>archive</code> in the same directory Hypermail was run from.
</ol>
<p>
Note that Hypermail can only read messages in the UNIX mailbox format! Such archives are typically RFC 822 mail messages appended to each other that look similar to this:
<p>
<pre>
From john@foo.com Mon Jan 1 00:01:30 1994
Date: Mon, 1 Jan 1994 00:01:15 PDT
From: john@foo.com
To: everyone@foo.com
Subject: Hello, world!
Hi, everyone, just saying hello!
From someone.else@foo.com Mon Jan 1 00:02:00 1994
Date: Mon, 1 Jan 1994 00:01:45 PDT
...
</pre>
<p>
The messages are typically separated by lines in this format:
<p>
<pre>
From www-talk@www0.cern.ch Fri Jul 1 00:18:20 1994
</pre>
<p>
The <b>-c</b> option tells Hypermail to read in settings from a configuration file. By default, the program will attempt to read settings from a file called <code>.hmrc</code> in the user's home directory if it exists.
<p>
In the configuration file, variables are set in the following manner:
<p>
<pre>
set hm_variable = number
set hm_variable = "string"
</pre>
The complete set of variables that Hypermail recognizes is described in the <a href="#4">Configuration Options</a> section.
The <b>-l</b> option tells Hypermail what to call the archive - the name that is specified will be in the title of the index pages so users know what sort of messages are being archived.
<p>
The <b>-a</b> option includes a link labelled "Other mail archives" in the index pages to any specified URL. This way users who are looking at the archive have the opportunity to go to pointers to other mail archives. By default, this will be a pointer to the parent directory in which the archive files reside.
<p>
The <b>-b</b> option includes a link labelled "About this archive" in the index pages to any specified URL. This way users who are looking at the archive have the opportunity to go to information about the archive.
<p>
<pre>
example: hypermail -l "WWW-Talk Archives"
-a "http://foo.com/archives/"
-b "http://foo.com/archives/info.html"
</pre>
<p>
In the index files for the archive, the above setting will produce something like this:
<p>
<blockquote>
<code>(top of page)</code>
<p>
<b>WWW-Talk Archives</b>
<ul>
<li> <a href="http://foo.com/archives/info.html"><b>About this archive</b></a>
<li> <a href="http://foo.com/archives/"><b>Other mail archives</b></a>
</ul>
<p>
<code>(list of indexed articles below)</code>
</blockquote>
<p>
<a name="3.3"><b>Updating Options:</b><br></a>
<b>-x</b>, <b>-u</b>
<p>
The <b>-x</b> option tells Hypermail to explicitly overwrite any previous HTML files that may exist. Use this option only when it is desirable to completely rewrite the entire archive.
<p>
The <b>-u</b> option tells Hypermail to update the archives by one message only. With this option, only one email message will be read in from a file or standard input. This message will be added to the end of the existing HTML file archive and will be integrated into it by links and cross-references. All archive index files will be regenerated to include the new message.
<p>
<b>Important!</b> - If the <b>-u</b> option is used and Hypermail is reading from a mailbox file, Hypermail will assume that the file contains only one article, no matter how many files the mailbox may actually contain. Make sure that Hypermail is given only one article when using this option.
<p>
If the mailbox that is being read from is an archive that new messages are always being added to, don't use either of these options. Hypermail will then read in all the messages given it but will only write new messages that have been appended to the mailbox.
<p>
<pre>
example 1: cat "one.letter" | hypermail -i -u -d "/www-talk"
example 2: hypermail -i -u -m "one.letter" -d "/www-talk"
example 3: hypermail -m "mailbox" -d "/www-talk" -x
example 4: hypermail -m "mailbox" -d "/www-talk"
</pre>
<p>
<ol>
<li> This tells Hypermail to take the article it receives from standard input and integrate it with the archive under the <code>www-talk</code> directory. If no archive exists, a new one will be created with the specified letter as the first file of the archive.
<p>
<li> This does the same thing, except that the letter is read in from a file that contains only that letter.
<p>
<li> With these options, Hypermail will read in the articles from <code>mailbox</code> and write over any existing files in the <code>www-talk</code> directory if they exist. If no archive exists, a new one will be created.
<p>
<li> With these options, Hypermail will read in the articles from <code>mailbox</code> and only write new articles - it will not overwrite any existing archive files.
</ol>
<p>
Note that no matter what options are specified, the index files are always rewritten. The date when Hypermail was last run is included in index pages, so it's easy to tell when the archive was last updated.
The <b>-p</b> option shows a progress report as Hypermail reads in and writes out messages - the number of files that Hypermail is reading and writing and the file names of the directory and files created are shown.
<p>
<hr>
<a name="4"><h1>Configuration Options</h1></a>
Hypermail has many variables that can be set as environment variables or as variables in the specified configuration file. For instance, using the C shell, one could define variables in this manner:
<p>
<pre>
setenv HM_MBOX /home/john/my_mailbox
setenv HM_FILEMODE 0600
</pre>
<p>
In the configuration file, variables must be in lowercase and separated by their values with an equals (<code>=</code>) sign. Blank lines and lines beginning with the <code>#</code> character are skipped:
<pre>
set hm_mbox = "/home/john/my_mailbox"
set hm_filemode = 0600
</pre>
<p>
Settings are read in this order:
<p>
<ol>
<li> From the program's hard-wired internal defaults,
<li> From environment variables,
<li> From command-line options,
<li> From the configuration file.
</ol>
<p>
Below is a list of configuration variables that can be defined. Boolean numbers can have the value of 0 or 1.
<p>
<dl>
<dt> <code>HM_CONFIGFILE "filename"</code>
<dd> This is the default configuration file to read settings in from. This can only be specified as an environment variable. If the first character is "~", Hypermail will look for the file under the current user's home directory.
<p>
<dt> <code>HM_MBOX "filename"</code>
<dd> This is the default mailbox to read messages in from. Define this with a value of <code>"NONE"</code> to read from standard input as the default.
<p>
<dt> <code>HM_ARCHIVES "URL"</code>
<dd> This will create a link in the archived index pages to the specified URL. Define as <code>"NONE"</code> to omit such a link.
<p>
<dt> <code>HM_ABOUT "URL"</code>
<dd> This will create a link in the archived index pages to the specified URL. Define as <code>"NONE"</code> to omit such a link.
<p>
<dt> <code>HM_REVERSE boolean_number</code>
<dd> Defining this variable as <code>1</code> will reverse-sort the article entries in the date and thread index files by the date they were received. That is, the most recent messages will appear at the top of the index rather than the other way around.
<p>
<dt> <code>HM_SHOWHEADERS boolean_number</code>
<dd> Define this as <code>1</code> to show the article header lines in the archived HTML files. These lines typically include the "To:", "From:", and "Subject:" information found in most email messages.
<p>
<dt> <code>HM_SHOWHTML boolean_number</code>
<dd> Define as <code>1</code> this to show the articles in a proportionally-spaced font rather than a fixed-width (monospace) font. Defining this option will also tell Hypermail to attempt to italicize quoted passages in articles.
<p>
<dt> <code>HM_LABEL "label name"</code>
<dd> Define this as the default label to put in archives.
<p>
<dt> <code>HM_DIR "directory"</code>
<dd> This is the default directory that Hypermail will look for when creating and updating archives. If defined as <code>"NONE"</code>, the directory name will be the same name as the mailbox read in.
<p>
<dt> <code>HM_DIRMODE octal_number</code>
<dd> This is an octal number that new directories are set to when they are created. If the archives will be made publically available, it's a good idea to define this as <code>0755</code>. If files will be updated incrementally with sendmail, this will have to be <code>0777</code>.
<p>
<dt> <code>HM_FILEMODE octal_number</code>
<dd> This is an octal number that new files are set to when they are created. If the archives will be made publically available, it's a good idea to define this as <code>0644</code>. If files will be updated incrementally with sendmail, this will have to be <code>0666</code>.
<p>
<dt> <code>HM_OVERWRITE boolean_number</code>
<dd> Define as <code>1</code> to make Hypermail overwrite existing archives by default.
<p>
<dt> <code>HM_INCREMENT boolean_number</code>
<dd> Define as <code>1</code> to read one article only and append it to existing archives by default.
<p>
<dt> <code>HM_PROGRESS boolean_number</code>
<dd> Define as <code>1</code> to always show a progress report as Hypermail works.
<p>
<dt> <code>HM_THRDLEVELS number</code>
<dd> This specifies the number of thread levels to outline in the thread index. For instance, if <code>THRDLEVELS</code> is <code>2</code>, replies to messages will be indented once in the index, but replies to replies, etc., will only be indented once as well.
<p>
<dt> <code>HM_DEFAULTINDEX "type"</code>
<dd> This is the index that is intended to be the one that users see first when entering the archive. Possible values are <code>"date"</code>, <code>"thread"</code>, <code>"subject"</code>, and <code>"author"</code>.
</dl>
<p>
There are a few <code>#define</code> options which can only be changed in the source code:
<p>
<dl>
<dt> <code>SHOWBR</code>
<dd> When defined, <code><br></code> tags will be placed at the end of article lines. Otherwise, all non-quoted article lines will word wrap. This only takes effect if <code>SHOWHTML</code> is defined.
<p>
<dt> <code>IQUOTES</code>
<dd> When defined, Hypermail attempts to italicize quoted lines. This only takes effect if <code>SHOWHTML</code> is defined.
<p>
<dt> <code>SHOWHR</code>
<dd> When defined, horizontal rules are placed before and after articles.
<p>
<dt> <code>EURODATE</code>
<dd> When defined, article received dates will appear with days before months instead of months before days.
<p>
<dt> <code>SHOWREPLIES</code>
<dd> When defined, all replies to a message will be shown as links in article files.
<p>
<dt> <code>MAILCOMMAND "command"</code>
<dd> This specifies the mail command to use when converting email addresses to links. Variables can be used in constructing the command string:
<p>
<ul>
<li> <code>$TO</code> represents the address to send mail to,
<li> <code>$SUBJECT</code> represents the subject that is being replied to, and
<li> <code>$ID</code> represents the message ID of the article that is being replied to.
</ul>
<p>
If <code>MAILCOMMAND</code> is not defined, email addresses will not be converted to links in articles. A possible command one could use is <code>"mailto:$TO"</code>, but this could easily be changed to specify a CGI program such as <code>"/cgi-bin/mail?to=$TO"</code>. A CGI mail program is included with the source which can be used for this purpose.
</dl>
<p>
<hr>
<a name="5"><h1>Other Things</h1></a>
<b>Filenames:</b> In the specified directory, articles will be read out in the order that they were read in from a mailbox or standard input. Filenames start at zero and increase in this fashion: <code>0000.html</code>, <code>0001.html</code>, <code>0002.html</code>, etc. In the same directory:
<p>
<ul>
<li> <code>date.html</code> is the index of articles sorted by the date they were received by the system's mail daemon.
<li> <code>thread.html</code> is the index of articles sorted by thread first, then the date they were received.
<li> <code>subject.html</code> is the index of articles sorted by subject. Any "Re:" prefixes in front of subjects will have been stripped out.
<li> <code>author.html</code> is the index of articles sorted by the first word of the author's name. If the author's name can't be determined, their email address will be substituted.
<li> One of the above files will be called <code>index.html</code> and is the default index that users can go to when entering the archive.
</ul>
<p>
<b>Sorting:</b> In the date and thread index files, note that these lists are sorted by the date the articles were received by the system's mail daemon, not by the date they were written on. The order of articles in the date index may not necessarily match the order in which the article files are written and linked together. Because of this, it is a good idea to make sure the mailbox is sorted by date with the most recent messages towards the bottom.
<p>
<b>Running Hypermail automatically:</b> All that's needed to start archiving email messages is to set up Hypermail to do incremental updates in your <code>/etc/aliases</code> file. Here's what an entry might look like (the last line is one unbroken line):
After adding the entry, make sure <code>newaliases</code> is run to update the mail aliases. This entry will run Hypermail and update/create the archive whenever a new message is received. Hypermail also works well as a <code>cron</code> job. Because <code>sendmail</code> may run Hypermail as different users (this is a well-known <code>sendmail</code> bug), you will want to make sure that archive directories and files are made readable and writeable by everyone when they are created. This will ensure that there will be no problems incrementally updating the archive.
<p>
<b>Including HTML in messages:</b> One can include formatted HTML in message bodies by enclosing the HTML with the <HTML> tag (in either uppercase or lowercase). This tag must be on a line by itself:
<p>
<pre>
This text will not be parsed...
<html>
<b>this text</b> will be parsed as HTML.
</html>
This text will not be parsed...
</pre>
<p>
There is no limit to how often the <HTML> tag can be used in an article.
<p>
<hr>
<a name="6"><h1>Getting Hypermail</h1></a>
All versions of Hypermail are available free of charge under a license agreement. It allows free use for noncommercial purposes, and protects against unauthorized commercial distribution. To view the agreement and download the software, open your World-Wide Web browser to <a href="http://www.eit.com/software/hypermail/">http://www.eit.com/software/hypermail/</a>.
<p>
Hypermail binaries are available for the following platforms:
<p>
<ul>
<li> SunOS 4.1.3
<li> Solaris 2.3 <li> IRIX 5.2
<li> OSF/1 2.0
</ul>
<p>
The Common Lisp version of Hypermail has had no formal version number and differs in many ways from the current C version. The latest documentation of the C version can always be found at <a href="http://www.eit.com/software/hypermail/hypermail.html">http://www.eit.com/software/hypermail/hypermail.html</a>.
<p>
<ul>
<li> Please send any feature requests, bug fixes, and comments on the C version of Hypermail to Kevin Hughes at <a href="mailto:kevinh@eit.com">kevinh@eit.com</a>. Requests, fixes, and comments on the Common Lisp version <b>only</b> should be sent to Tom Gruber at <a href="mailto:gruber@ksl.stanford.edu">gruber@ksl.stanford.edu</a>.
<li> Due to the inordinate amount of email Kevin gets, he makes no promises that he will have time to respond to your message. He will eventually read everything you send him, however.
<li> <b>If you have questions about licensing</b>, please send email to Elizabeth Batson, <a href="mailto:batson@eit.com">batson@eit.com</a>. She should only be contacted if you have licensing or business related questions.
<li> The Acorn part of this document has been written by Roger Horne, <a href="mailto:roger@number7.demon.co.uk">(roger@number7.demon.co.uk)</a> who is also the person who took a blunt instrument to the original source code and got it to work on the RISC PC.
